Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-20/pb911221.zip/PBDOC001.ASC

Text File | 1991-12-21 | 16KB | 400 lines

PB
User's Documentation Rev. 0.01

Rev 0.01 (as of version PB 911221r):

Added "exitafter" in section 2.3.6
Removed warning r.e. "actdays". 2.3.5
Bug in slist.dat fixed. Those who ever used version 911220s read file
"slistfix" and carry out fix procedure.
=============================

The PACSAT Broadcast Groundstation Program

This documentation relates to versions of PB with version dates 911220 or
newer. Users of older PB versions are strongly encouraged to update!

PB is an groundstation program for receiving messages and message directories
from satellites running the PACSAT Protocol Suite. AO-16, LO-19, UO-14 and UO-
22 are all compatible with this software.

[As of 21/12/91, only UO-14 supports the broadcast directory system used by
PB. The other satellites should follow by mid January 1992.]

PB will run on any IBM compatible Personal Computer running MS-DOS. [Version
5.0 and 3.x have been extensively tested.] Although PB will run on a PC or XT
machine, serious users of UO-14 and UO-22 will desire at least a 12 MHz AT. A
hard disk or ramdisk is also necessary.

PB requires a terminal node controller (TNC) which supports the KISS interface
mode. TNCs with KISS EPROMs are supported, as are TNCs which recognise the
TAPR-style commands for entering KISS mode.


1 PRINCIPALS OF OPERATION

Two aspects of PB and PACSAT operation are unfamiliar to users of terrestrial
packet radio: the client/server relationship and the use of "broadcast mode".
Both of these concepts are essential to an in-depth understanding of PB.

1.1

1.2 Message Status

When you are in the Directory View window, you can see a message's status in
the column headed "S". [Although I am looking at more colorful and cryptic
markers] the status markers are interpreted as follows:

n - Never

This message will not be automatically downloaded and filled, nor will it be
saved if it is overheard when another station is downloading it.

g - Grab

This is the next step up from "Never". It means that the message will be saved
if it is overheard when another station is downloading it, but it will not be
automatically filled.

A - Automatic

This is the standard automatic status. It means that the message will be
completely downloaded and filled automatically, without your intervention by
the PB program. When the message is completely filled, it will go to the
SQUARE BLOCK. [which is a pain in the ... when writing ASCII documentation].

P - Priority automatic

This allows you to place some messages "before" others in the automatic
downloading system. All messages with Priority will be downloaded and filled
before any messages with merely Automatic status. This is useful if you want a
short message which is "behind" a longer message that you have marked
Automatic.

SQUARE BLOCK - Downloaded

The message has been completely downloaded. When this first happens, the
message will be in the PB working directory, with the name xxxx.DL, where xxxx
is replaced by the message number.

E - Error (permanent)

The server has indicated that this message cannot be downloaded. Either it is
not there or you are not allowed access to it. This status is permanent, until
you change it manually.

e - Error (temporary)

The server has indicated that the message cannot presently be downloaded, but
might become downloadable later. This status is cleared when you exit PB and
the previous (A/P) status is restored.


N.B. - If you changed the status of a Downloaded message to A/P/g, you will
receive another copy of that message.

2.  PB.CFG CONFIGURATION OPTIONS

When it is run, PB reads a configuration file. The default file name is
PB.CFG, and it must be in the current DOS directory. Alternatively, you can
specify the complete DOS path to and name of the configuration file. (If you
specify the path/filename, you will probably also need a "pbpath" entry in the
config file to make sure that PB actually looks for and stores all of its
files where you really want them. See below.) The configuration file must be a
pure ASCII file like AUTOEXEC.BAT or CONFIG.SYS. It must not be edited with a
normal word processor which may insert control characters.

A sample configuration file comes with the PB program release. Some entries
you must edit. Others you might need to. Others you can if you want to. Others
you are discouraged from editing.


2.1 MUST EDIT:

2.1.1 mycall <call>[-<ssid>]

Your station callsign. <call> is 6 or fewer ascii characters. <ssid> is an
optional number from 1 to 15. Please do not use an <ssid> unless you have a
very good reason.

2.2 MAY EDIT:

2.2.1 alias <string>

Other names you might be called. This is used during automatic message
scanning. For example, people sometimes mess up my callsign when sending me
messages, so I also have

alias K8KA

in my file. That way if they send messages to "gok8ka" or "g/k8ka" PB will
still find them and download them for me.

2.2.2 bdcstcall <call>[-<ssid>]

This identifies the satellite you want to communicate with. The distribution
file is for UOSAT3-11, so when you make a configuration file for another
satellite, you'll need to change this. Some other satellite calls are:
     pacsat-11
     lusat-11
     uosat5-11

2.2.3 port 1|2
          Default COM1

Sets the communications port. Only COM1 and COM2 are supported. This is the
port your TNC should be connected to. If you normally use a TSR serial
communications driver (COMBIOS, MBBIOS, etc) remove it before running PB.

2.2.4 speed <baud rate>
          Default 19200

This is the speed that you have your TNC asynchronous port set to. This is not
directly related to the downlink or uplink speed of the satellite, although it
is recommended that you run your asynchronous port faster thatn your satellite
port. For UO-14 and UO-22 this means running the asynchronous port at 19200
baud.

2.2.5 pbpath <dos path>
          Default is the current logged directory

PB will look for and create certain data and message files during its
operation. If you don't have a "pbpath" entry in your configuration file, PB
will use the currently logged DOS directory. If you want to make sure you know
where PB is putting its files, put a "pbpath" entry in the configuration file.
For example

pbpath c:\pacsats\uosat3

would tell PB to find/put all data and message files in the directory
"\pacsats\uosat3" on drive C.

2.2.6 txd <tx keyup delay msec>
          Default 150 msec
This is the number of msec between the keying of your transmitter and the
transmission of data.

2.2.7 restart_delay <delay after restart cmd>
          Default 60  (in 1/18 second increments, e.g. 3.333 seconds)
This delay tells PB how long your TNC takes to get into KISS mode. Most TNCs
flash their lights 3 times while entering KISS mode, and PB must not try to
communicate with the TNC during this time.

2.2.8 aea_delay <delay before restart cmd>
          Default 1 (as above, e.g. 0.055 seconds)
This delay is necessary on some "smart" TNCs. If your TNC won't go into KISS
mode, then try bumping this up a lot to cure it.

2.2.9 break_delay <delay after break>
          Default 9 (as above, e.g. 0.5 seconds)
This delay allows the TNC to get its cmd: processor sorted out before we try
to send commands to the TNC.

2.2.10 silent 0|1
          Default 0
Set slient to 1 if you don't want any warning bells.

2.2.11 kisstnc 0|1
          Default 0
If you have KISS EPROMs in your TNC, or otherwise put your TNC into KISS mode
before running PB, set this to 1.

2.2.12 paclen <bytes>
          Default 244
When your station requests something from the satellite, it asks the satellite
to transmit packets of this length. If you have not set up your downlink
receiver for peak performance, you may wish to recduce this length. In
general, you should not change this.

This has no effect on uplink packet size.

2.2.13 trace 0|1
          Default 0
Little general importance. Trace is used to monitor connected mode activity on
the downlink.

2.2.14 tncid <id>
          Default 0
Little general importance. Allows you to set a multidrop KISS address.

2.2.15 ndupesearch <depth>
          Default 100
Very little general importance. When a new directory entry is received from
the satellite, it may be for an updated version of a spacecraft log file. PB
will scan the newest <depth> entries in your directory to find out if this is
true.

2.2.16 maxpfhsize <bytes>
          Default 500
Very little general importance. The PFH is the header or envelope which
encloses messages on the PACSAT server. This PFH is also the "directory entry"
which PB stores for the directory view mode. PFHs can be any length. If people
start using really big ones, you might have to increase this number. A message
will show up in the message window if this is ever the case.

2.2.17 logbbframes 0|1
          Default 0
Little general interest. If 1, put all broadcast protocol data frames in the
KISS log.

This and the next two entries (logdbframes, logothers) control what KISS
frames get stored in the KISS log files. KISS log files are "raw output" from
your KISS TNC. They are stored in files called yymmddhh.KSS, where yymmddhh is
replaced by the current time. These files are useful for debugging or for
keeping statistics.

2.2.18 logdbframes 0|1
          Default 0
Little general interest. If 1, put all directory broadcast protocol frames in
the KISS log.

2.2.19 logothers 0|1
          Default 0
Some general use. If 1, put all frames which are not broadcast directory or
data frames into a KISS log file. This might be used to capture telemetry
frames for later processing.

2.3 CONTROL OF AUTOMATIC OPERATION AND FILE MAINTAINANCE

2.3.1 dirupdatemins <minutes>
          Default 15
Tells how many minutes after bringing the directory up-to-date, the directory
should be updated again. This is set to some time greater than the average
pass, and allows PB to be left running overnight. The directory will then be
updated every pass, even though you haven't quit and re-run PB.

2.3.2 autoselect 0|1
          Default 1
If this is 1, PB will automatically check every new received directory entry
to see if the message has your call or alias in the DESTINATION: field. If so,
the message will be marked for Automatic downloading and hole filling.

2.3.3 blockftype <decimal file type>
          Default none.
You can have up to 10 "blockftype" entries in your configuration file. Each
one specifies a certain type of file that you don't want to receive (unless
you specifically, manually mark it A, G or P).

(If autoselect and blockftype disagree about a file, autoselect wins.)

2.3.4 graball 0|1
          Default 1
Because of the way broadcast mode works, you may hear part of a message being
transmitted to someone else before you have received the directory entry (PFH)
for that message. If you have graball on, these bits of messages will be
captured and saved unless they are blocked by a "blockftype" entry.

N.B. I WOULD GREATLY APPRECIATE IT IF EVERYONE LEFT THIS FLAG AT 1. THIS WILL
ALLOW THE GREATEST RE-USE OF PACKETS ON THE DOWNLINK AND WILL MAKE THE
SATELLITE MORE USEFUL FOR EVERYONE. IF YOU ARE WORRIED ABOUT THE PRLIFERATION
OF .ACT AND .HOL FILES, SEE 2.3.5 IMMEDIATELY BELOW AND MAKE GOOD USE OF
"BLOCKFTYPE".

2.3.5 actdays <days>
          Default 3
Tells PB how long to keep grabbed message fragments. If you set this to 0, all
partially-received messages will be deleted immediately when you exit PB. This
is better than turning "graball 0".

2.3.6 showgrabs 0|1
          Default 0
If 1, then every time a broadcast message packet is heard, a cryptic
explaination of why it is/isn't being grabbed will be printed in the Message
Window.

2.3.6 exitafter <minutes>
          Default 0
If this is not 0, PB will exit if it hasn't heard a packet for the given
number of minutes.

3.0 CONTROL KEYS

Control keys are now used to toggle ON/OFF certain aspects of PB operation.

ctrl-a     Toggle automatic operations on/off.
ctrl-z     Zoom/Unzoom the Downlink Window.
ctrl-d     Toggle the display of data bytes in the Downlink Window.
ctrl-t     Toggle trace mode in the Downlink Window.
ctrl-h     Toggle the display of AX.25 headers in the Downlink Window.
ctrl-x     Toggle the hexadecimal display of data in the Downlink Window.
ctrl-k     Toggle the status of the "logothers" flag. See 2.2.19.
ctrl-g     Toggle the status of the "graball" flag. See 2.3.4. DON'T DO IT.


4.0 MENU SELECTIONS

There are two menus. One is the "Main Menu" and the other is the "Directory
View Menu". You will generally want to interact with PB through the Directory
View Menu. Each menu has a (H)elp option which you should read.

4.1 Directory View Menu


P, A, G, or N to change the status of the message currently hilighted by the
cursor. See 1.2 Above for descriptions of the various status settings.

Right Arrow to see an expanded view of the Subject and Keywords fields.

Left Arrow to return to the normal view.

ENTER to see a quasi-complete display of the message header (PFH).

Up and Down Arrows move the cursor.

Page Up and Page Down. To change the display page. [HOME/END coming soon.]

Q to Quit the program, that is to leave PB completely.

M or ESC to return to the Main Menu.

H to see the help screen for Directory View mode.

The function keys are [a first, inflexable implementation of] directory
display filters:

F1 - to show all directory entries.
F2 - show only those entries with your call or alias in the To field.
F3 - show only those entries with "all" in the To field.
F4 - show only spacecraft log files (AL, CP, etc.). [Not 100% filtered.]
F5 - show Downloaded messages
F6 - show Automatic and Priority messages
F7 - show Grab, Automatic and Priority messages
F1 - to show all directory entries.

4.2 Main Menu

Download: Priority Auto Grab Never Fill Dir   Info. View dir. Quit! Help.

4.2.1 Priority, Auto, Grab and Never

These operate the same as they do on the Directory View Menu, except that you
will be prompted to enter the desired message number. This is primarily used
to request messages before you have received their Directory, and is of little
use.

4.2.2 Fill

This is a manual command which tells PB to request a particular message from
the If you have not yet received any part of the message, Fill will request
that the satellite transmit the entire message for you. satellite. If you
already have part of the message, Fill will request only the missing portions
("holes"). Fill does not alter the message status, and the message will not be
automatically completely filled unless it is already marked by the A or P
command.

If you want to use Fill instead of allowing PB to operate automatically, type
ctrl-A to turn automatic mode off. This will be indicated by "Auto: Disabled"
on the Status Bar.

4.2.3 Dir

This sends a directory request to the satellite, to update your directory.
This is an immediate, manual command. Generally, the directory will be updated
when you run PB, after PB has downloaded any messages with Automatic or
Priority status. It is best to let PB automatically update your directory
after Automatic and Priority operations are complete, since this gives you the
best opportunity to re-use other people's directory entries.